Addendum MessageService 3.1
Versie: Addendum Messageservice v3.1
Addendum
In dit addendum worden vijf zaken nader uitgelicht. Het addendum moet worden gelezen samen met de technische documentatie van de MessageService 3.1. Dit addendum geeft een nadere verheldering van terminologie en functies die reeds tot de mogelijkheden van de MessageService behoorde, daarbij worden er geen nieuwe functionaliteiten toegevoegd. Omdat security belangrijker is, zijn er een tweetal adviezen toegevoegd rond de verbinding en het gebruik van nonces. Ook wordt er één fout in een voorbeeld hersteld. Door vragen uit de markt is dit addendum noodzakelijk geacht door de Techniek Commissie en is van toepassing op de laatste versie van de MessageService, te weten de MS3.1. De inhoud van het addendum is onderdeel van de MS3.1.
Verbreding termen Klant en Leverancier
In het gehele document van de Technische Handleiding voor de MS3.1 wordt gesproken over klant en leverancier. In die context was de leverancier vaak de groothandel en de aannemer en/of installateur de klant. Dit principe dient losgelaten te worden. Zie bijlage 1.
De PostMessage functie nader uitgelegd
De beschrijving van de PostMessage functie wordt uitgebreid met een server-server methode. Ook is de terminologie hierop aangepast, zie bijlage 2.
Advies alleen https-communicatie te gebruiken
In paragraaf 1.3.2 van de technische documentatie van de MessageService 3.1 wordt nog gesproken over het gebruik van HTTP en HTTPS. Via dit addendum wordt sterk geadviseerd om alleen HTTPS te gebruiken, omdat er ook inloggegevens met de MessageService worden verstuurd. Dan is HTTPS veel veiliger dan HTTP. Tevens moet gelet worden op de geldigheid van de TLS protocollen (Transport Layers Security). Er zijn verschillende websites waar dat gecheckt kan worden (zoals, https://www.ssllabs.com/ssltest/).
Omgaan met Nonces
In paragraaf 1.3.3.3 van de technische documentatie van de MessageService 3.1 staat het volgende: “(Toelichting: password versturen in plain tekst)”. Als partijen bilateraal nonces willen gebruiken om daarmee de veiligheid te vergroten dan is dat toegestaan. Ga er wel vanuit dat met andere partijen plain tekst de standaard kan zijn.
Foutief voorbeeld figuur 1.6
Figuur 1.6 in paragraaf 1.3.4 van de technische documentatie van de MessageService 3.1 is fout. De “MsgProperties” zijn onderdeel van de “Message”. In de WSDL staat dit wel juist. Het voorbeeld dat getoond zou moeten worden, heeft alleen betrekking op de MsgContent. Het figuur is aangevuld met een tweede escape voorbeeld welke beide voldoen aan de W3C standaard.
Voorbeeld 1:
<MsgContent>
<?xml version="1.0" encoding="UTF-8"?>
<xml-bericht>
</xml-bericht>
</MsgContent>
Alle verboden tekens zijn escaped.
Voorbeeld 2:
<MsgContent>
<?xml version=”1.0” encoding="UTF-8"?>
<xml-bericht>
</xml-bericht>
</MsgContent>
Alleen de strikt noodzakelijke tekens zijn escaped.
Dubbel escapen
Als uitbreiding van paragraaf 1.3.4 van de technische documentatie van de MessageService 3.1 willen we een toelichting geven op het escapen. Als een XML bericht via de MessageService als payload in de MsgContent verstuurd wordt, wordt dit gehele bericht gezien als data. Eventuele ampersand tekens van eerdere escape acties zullen dus ook in deze stap escaped moeten worden, het dubbel escapen. Zo kan worden gegarandeerd dat bij het de-escapen het oorspronkelijke XML bericht weer terugkomt.
Bijlage 1
De MessageService faciliteert de communicatie tussen twee partijen. Echter zullen partijen zakendoen met andere partijen en vice versa. Derhalve dienen beide partijen in hun software hier rekening mee te houden. Echter door de keuze voor een “server – cliënt” of “server – server” situatie kunnen niet alle functies van toepassing zijn. In beide situaties is er wel sprake van een partij welke het initiatief neemt tot communicatie (partij A) en een partij welke dit initiatief ontvangt (partij B).
Partij A
- Heeft een uniek ApplicationId dat gebruikt wordt in de communicatie zodat de software weet met welke softwareapplicatie ‘gepraat’ wordt en op basis hiervan kan vastgelegd worden welke berichtenversies uitgewisseld moeten worden. Geadviseerd wordt om voor het ApplicationId een GLN te gebruiken.
- Per serverpartij moet vastgelegd worden:
- URL waarop de MessageService van die partij bereikbaar is, het zogenaamde end point.
- Gebruikersnaam (eventueel aangevuld met een relatie code) en een wachtwoord waarmee ingelogd kan worden bij partij B.
Alle partijen die gebruik maken van de MessageService kunnen de verbinding oproepen met dezelfde cliënt, slechts de hierboven genoemde gegevens verschillen en dienen instelbaar te zijn per partij.
Partij B
- Heeft per ApplicationId (en eventueel versie) vastgelegd:
- Welke berichttypen het softwarepakket kan ontvangen.
- In welk berichtformaat de software de berichten wil ontvangen.
- Welk versienummer van dat berichtenformaat de software wil ontvangen.
- Per partij vastleggen welke berichten de partij wil ontvangen in welk ApplicationId.
- De berichten vastleggen in een database per partij/ApplicationId.
Bij berichten vastleggen wanneer het bericht aangemaakt is in de database, monitoren of partijen het opgevraagd hebben en wanneer na een bepaalde periode het bericht nog niet opgevraagd is kan er een actie ondernomen worden.
Bijlage 2
De communicatie tussen de cliënt en de server kan getriggerd worden vanuit beide partijen. Gezien het feit dat de Commissie bepaald heeft geen eisen aan de omgeving te willen stellen, moeten partijen gezamenlijk overeenkomen welke methode gekozen wordt voor de uitwisseling van de berichten.
Er zijn 2 situaties te onderscheiden, deze worden verder uitgewerkt:
- Server – Cliënt
- Server – Server
Definitie: Binnen deze documentatie wordt er bedoeld met server dat een systeem ‘altijd’ bereikbaar is, en met client een systeem dat niet altijd bereikbaar is (zoals een laptop). Welke situatie van toepassing is zal per relatie afgestemd moeten worden. Inclusief de “rolbepaling” tussen de communicerende partijen. Dus wie is per situatie Partij A en wie is Partij B? Dit is met name van toepassing bij een server – cliënt situatie. Deze bovenstaande situaties kunnen niet gemengd worden toegepast tussen 2 partijen. Dus binnen een relatie tussen partij A en B kan maar één situatie voorkomen.
Toepassing Server – Cliënt
Communicatie van cliënt -> server
Wanneer de cliënt een bericht aan de server stuurt is dit eenvoudig in te richten. Uitgangspunt is dat er een server is ingericht met daarop de MessageService waar de cliënt tegenaan kan ‘praten’. Dit ziet er schematisch als volgt uit:
Figuur 1 - Schema communicatie
Bovenstaand schema kan zowel voor synchrone (vraag-antwoord spel) alsook voor asynchrone communicatie gebruikt worden. Bovenstaand schema kan ook gebruikt worden voor communicatie via een hub.
Communicatie van server -> cliënt
Wanneer de server een bericht wil sturen aan de cliënt (asynchroon) dan is de moeilijkheid dat in de randvoorwaarden staat dat aan de (IT) omgeving van de cliënt geen eisen gesteld mogen worden. Derhalve kan het schema zoals dat in de vorige paragraaf staat niet eenvoudigweg omgedraaid worden omdat de cliënt dan zou moeten beschikken over een server. Daarom is gekozen voor een andere oplossing waarbij de partij met de server de berichten klaar zet en de cliënt periodiek de berichten ophaalt. Geadviseerd wordt om minimaal 1 maal per dag te controleren of er berichten zijn, daarnaast moet de gebruiker in de software zelf het initiatief kunnen nemen om te bekijken of er nog berichten klaarstaan. Schematisch ziet dat er dan als volgt uit:
Allereerst vraagt de cliënt een lijst met berichten op die klaarstaan bij de server. De server geeft terug welke berichten er klaar staan.
Figuur 2 - Schema berichten die klaar staan
Vervolgens vraagt de cliënt elk bericht één voor één op, de server geeft in het antwoord het bericht terug.
Figuur 3 - Schema opvragen berichten
Als de cliënt het bericht succesvol ontvangen heeft geeft hij dat aan bij de server zodat de server het bericht kan verwijderen of kan markeren als opgehaald.
Figuur 4 - Schema ontvangen, markeren of verwijderen bericht
Toepassing Server – Server
Een andere situatie doet zich voor als beide partijen beschikken over een server, in dat geval is bovenstaande situatie minder efficiënt omdat er dan (semi-)continue bevraagd moet worden of er berichten klaar staan. De berichten worden direct afgeleverd, bij aflevering volgt een standaard MessageResult (zie paragraaf 2.4 PostMessage functie in de originele documentatie) of een opvolgend bericht naar aanleiding van het verstuurde bericht. Het is dan ook niet nodig berichten te verwijderen, ze staan immers ook niet klaar. Zie onderstaand schema:
Figuur 5 - Schema server naar server communicatie